Naval  Research  Laboratory 

Stennis  Space  Center,  MS  39529-5004 


NRL/MR/7320-07-9081 


Makefl5:  An  ADCIRC  Model  Fort.15 
Input  File  Creation  GUI  for 
Parameter  Specification  and  Periodic 
Boundary  Forcing 


Cheryl  Ann  Blain 

Ocean  Dynamics  and  Prediction  Branch 
Oceanography  Division 

Robert  S.  Linzell 

Planning  Systems  Incorporated 
Stennis  Space  Center ;  Mississippi 


December  7,  2007 


Approved  for  public  release;  distribution  is  unlimited. 


REPORT  DOCUMENTATION  PAGE 


Form  Approved 
OMB  No.  0704-0188 


Public  reporting  burden  for  this  collection  of  information  is  estimated  to  average  1  hour  per  response,  including  the  time  for  reviewing  instructions,  searching  existing  data  sources,  gathering  and 
maintaining  the  data  needed,  and  completing  and  reviewing  this  collection  of  information.  Send  comments  regarding  this  burden  estimate  or  any  other  aspect  of  this  collection  of  information,  including 
suggestions  for  reducing  this  burden  to  Department  of  Defense,  Washington  Headquarters  Services,  Directorate  for  Information  Operations  and  Reports  (0704-0188),  1215  Jefferson  Davis  Highway, 
Suite  1204,  Arlington,  VA  22202-4302.  Respondents  should  be  aware  that  notwithstanding  any  other  provision  of  law,  no  person  shall  be  subject  to  any  penalty  for  failing  to  comply  with  a  collection  of 
information  if  it  does  not  display  a  currently  valid  OMB  control  number.  PLEASE  DO  NOT  RETURN  YOUR  FORM  TO  THE  ABOVE  ADDRESS. 


1.  REPORT  DATE  (DD-MM-YYYY) 

07-12-2007 


2.  REPORT  TYPE 

Memorandum  Report 


3.  DATES  COVERED  (From  -  To) 


4.  TITLE  AND  SUBTITLE 

Makefl5:  An  ADCIRC  Model  Fort.  15  Input  File  Creation  GUI 
for  Parameter  Specification  and  Periodic  Boundary  Forcing 


5a.  CONTRACT  NUMBER 


5b.  GRANT  NUMBER 


5c.  PROGRAM  ELEMENT  NUMBER 

0602435N 


6.  AUTHOR(S) 

Cheryl  Ann  Blain  and  Robert  S.  Linzell* 


5d.  PROJECT  NUMBER 


5e.  TASK  NUMBER 


5f.  WORK  UNIT  NUMBER 

73-6801-07-5 


7.  PERFORMING  ORGANIZATION  NAME(S)  AND  ADDRESS(ES) 

Naval  Research  Laboratory 

Oceanography  Division 

Stennis  Space  Center,  MS  39529-5004 


8.  PERFORMING  ORGANIZATION  REPORT 
NUMBER 


NRL/MR/7320— 07-908 1 


9.  SPONSORING  /  MONITORING  AGENCY  NAME(S)  AND  ADDRESS(ES) 

Office  of  Naval  Research 
One  Liberty  Center 
875  North  Randolph  Street 
Arlington,  VA  22203-1995 


10.  SPONSOR  /  MONITOR’S  ACRONYM(S) 

ONR 


11.  SPONSOR  /  MONITOR’S  REPORT 
NUMBER(S) 


12.  DISTRIBUTION  /  AVAILABILITY  STATEMENT 


Approved  for  public  release;  distribution  is  unlimited. 


13.  SUPPLEMENTARY  NOTES 

*Planning  Systems  Incorporated,  MSAAP  Building  9121,  Stennis  Space  Center,  MS  39529 


14.  ABSTRACT 

The  User’s  Manual  for  the  Makefl5  Graphical  User  Interface  (GUI)  software,  makefortl5gui.pl,  contains  descriptions  of  the  software,  including 
its  functionality  and  usage.  The  Makefl5  GUI  is  a  window-based,  platform-independent  Perl  script  that  can  both  create  or  modify  the  Advanced 
CIRCulation  (ADCIRC)  Model  Parameter  and  Periodic  Boundary  Forcing  File  (fort.  15).  The  software  was  developed  for  ADCIRC  version  45.11. 


15.  SUBJECT  TERMS 

ADCIRC  model  Tidal  forcing 

Parameters  Makefl5 


fort.  15 


16.  SECURITY  CLASSIFICATION  OF: 

17.  LIMITATION 

18.  NUMBER 

19a.  NAME  OF  RESPONSIBLE  PERSON 

OF  ABSTRACT 

OF  PAGES 

Cheryl  Ann  Blain 

a.  REPORT 

b.  ABSTRACT 

c.  THIS  PAGE 

UL 

32 

19b.  TELEPHONE  NUMBER  (include  area 

Unclassified 

Unclassified 

Unclassified 

code) 

(228)  688-5450 

Standard  Form  298  (Rev.  8-98) 

Prescribed  by  ANSI  Std.  Z39.18 


TABLE  OF  CONTENTS 


1.  Description .  1 

a.  Overview  of  the  GUI .  1 

b.  Software  Components .  6 

c.  Software  Prerequisites .  6 

d.  Software  Installation .  7 

2.  Fort.  15  Creation:  Using  makefortl5gui.pl .  8 

a.  Execution .  8 

b.  Specifications .  10 

3.  Details  of  the  GUI  Panel  Functionality .  14 

a.  The  General  Program  Options  Panel .  15 

b.  The  Time  Wetting/  Drying  Parameters  Panel .  16 

c.  The  Spatial  Structure  Parameters  Panel .  17 

d.  The  Friction,  Diffusion,  Viscosity  Panel .  17 

e.  The  Tidal  Potential  and  Periodic  Elevation/Flux  Boundary  Forcing 

Parameters  Panel .  17 

f.  The  Output  Station  Parameters  Panel .  19 

g.  The  Global  Output  Parameters  Panel .  21 

h.  The  Output  Harmonic  Analysis  Parameters  Panel .  21 

i.  The  GWCE  Solver  Parameters  Panel .  22 

j.  The  3-D  Model  Parameters  Panel .  22 

k.  The  3-D  Model  Input  Parameters  Panel .  22 

l.  The  3-D  Eddy  Viscosity  Parameters  Panel .  23 

m.  The  3-D  Temperature/Salinity/Density,  Velocity,  and  Turbulence 

Output  Parameters  Panel .  23 

n.  The  3-D  Global  Output  Parameters  Panel .  24 

o.  The  3-D  Diffusion  Parameters  Panel .  24 

4.  HELP  Features  of  the  GUI .  24 

5.  Error  Check  Provisions  in  the  GUI .  27 

6.  Known  Limitations .  28 

7.  Reference .  29 


-iii- 


1.  Description 


This  document  describes  the  Makefl5  Graphical  User  Interface  (GUI)  software, 
makefortl5gui.pl.  The  program  is  a  window-based,  platform-independent  Perl  script  that  can 
both  create  a  new  ADvanced  CIRCulation  (ADCIRC)  Model  Parameter  and  Periodic 
Boundary  Forcing  File  (fort.  15),  or  modify  an  existing  one.  This  software  was  developed  for 
ADCIRC  version  45. 1 1 . 

The  GUI  software  is  written  in  Perl  and  uses  the  Perl/Tk  module  for  the  graphics.  The  GUI 
design  aims  to  follow  the  structure  of  the  fort.  15  file  as  closely  as  is  feasible.  Related 
parameters  are  grouped  together,  and  are  kept  in  descending  order  corresponding  to  the 
fort.  15  file  wherever  possible. 

a.  Overview  of  the  GUI 

The  GUI  is  divided  in  to  several  sections  that  group  the  GUI  functions  and  the  fort.  15 
parameters  logically.  The  GUI  interface  is  shown  in  the  sequence  of  Figures  1  through  4, 
which  were  generated  on  a  Linux  platform  (Fedora  Core  3  and  Core  6)  using  the  Gnome 
(version  2.8.0)  and  KDE  (version  3.5.7)  desktop  environments.  Each  of  these  figures  presents 
a  view  of  the  GUI  as  it  is  scrolled  downward  one  screen  at  a  time  with  parameter  defaults 
assigned  (no  input  from  an  existing  fort.  15  file).  At  the  top  of  the  GUI  (Figure  1)  is  the  menu 
bar.  It  contains  a  File  menu  with  Open,  Save,  and  Quit  menu  items.  The  menu  bar  also 
contains  a  Help  menu  with  ‘About’  and  Fort.  15  Help  menu  items.  Below  the  menu  bar  is  the 
uppermost  panel  (Figure  1),  hereafter  referred  to  as  the  title  panel.  The  title  panel  is 
decorative  and  displays  the  Naval  Research  Laboratory  Detachment  Stennis  Space  Center 
(NRL-SSC)  and  Naval  Oceanographic  Office  (NAVOCEANO)  logos  with  the  ADCIRC  logo 
in  the  center.  The  remaining  panels  contain  the  fort.  15  model  parameters  in  logical 
groupings.  The  details  for  each  panel  are  described  in  §3.  It  is  beyond  the  scope  of  this 
document  to  describe  each  parameter  individually;  the  interested  reader  can  refer  to  the  on¬ 
line  ADCIRC  model  documentation  for  details  (found  at  http://adcirc.org:  Documentation^ 
User’s  Manual  v45  ->  Input  file  Descriptions Model  Parameter  and  Periodic  Boundary 
Forcing  File  (fort.  15)). 

Different  amounts  of  the  GUI  will  be  visible  depending  on  the  size  and  resolution  of  the 
screen  being  used.  The  GUI  can  be  resized  by  the  user  to  a  limited  extent  by  dragging  a 
comer  of  the  window  or  by  clicking  on  the  Maximize  button  in  the  upper  right  comer  of  the 
window.  The  width  of  the  GUI  is  limited  so  that  the  layout  does  not  change  if  the  window  is 
resized.  Similarly,  the  height  of  the  GUI  is  limited,  although  the  height  of  the  current  version 
may  be  greater  than  that  of  some  computer  monitors. 
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Figure  1.  A  display  of  the  topmost  page  of  the  Makefl5  GUI. 
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Figure  2.  A  display  of  the  second  page  of  the  Makefl5  GUI. 
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Figure  3.  A  display  of  the  third  page  of  the  Makefl5  GUI. 
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MakeFortl5  -  makefortl5gui.pl 


Figure  4.  A  display  of  the  final  page  of  the  Makefl5  GUI. 
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b.  Software  Components 

The  complete  Makefl5  GUI  tool  consists  of  sixteen  files  in  total: 

1 .  adcirc_banner_tiny.gif  -  A  GIF  image  file  with  the  ADCIRC  banner. 

2.  delt_interact.pl  -  A  Perl  script  that  calculates  the  mean  longitude  and  latitude  of  a 
finite  element  mesh  (FEM)  specified  by  the  fort.  14  file,  and  calculates  a  suggested 
time  step  for  tidally-dominated  flows  based  on  the  CFL  condition. 

3.  extract jgren.F  -  A  Fortran  90  program  that  extracts  tidal  boundary  forcing 
parameters  from  the  Grenoble  FES99  global  tidal  solution  database  (Lefevre  et  ah, 
2002). 

4.  Makefile  -  A  “makefile”  to  compile  the  executable  program  for  extractgren.F  and  its 
associated  subroutines. 

5.  Makefile _gfor.w32  -  A  sample  “makefile”  for  extract_gren.F  using  the  Windows® 
version  of  the  GNU  Fortran  compiler,  gfortran. 

6.  rnakefortl5gui.pl  -  The  Makefl5  GUI  Perl  source  code  and  executable  program. 

7.  navo_log.gif-  A  GIF  image  file  with  the  NAVOCEANO  logo. 

8.  nrlicon.gif  -  A  GIF  image  file  with  the  NRL  logo  in  icon  form. 

9.  nrltiny.gif—  A  GIF  image  file  with  the  NRL  logo. 

10 . pararn_defs_test.txt  -  An  ASCII  text  file  with  default  specifications  of  the  ADCIRC 
model  parameters. 

11.  README. makefortl 5gui  -  An  infonnational  “readme”  file  for  the  GUI  software. 

12.  README.tidefacl 5  -  Am  informational  “readme”  file  describing  certain  tidal  forcing 
parameters. 

13.  tablk2.f-  A  Fortran  subroutine  called  by  extract_gren.F. 

14.  tide_gren.dat  -  The  Grenoble  FES99  global  tide  solution  database. 

15.  tide_grenf—  A  Fortran  subroutine  called  by  extract  gren.F. 

16.  tide _fac.f  -  A  Fortran  program  to  calculate  tidal  node  factors  and  equilibrium 
arguments  for  the  periodic  boundary  forcing. 

All  of  these  files  must  be  present,  and  the  Fortran  programs  must  be  compiled  for  the 
platform  on  which  the  system  is  installed.  Note  that  the  file  tide_gren.dat  is  a  big-endian 
binary  file  requiring  compilation  of  the  extract jgren.F  program  with  appropriate  byte¬ 
swapping  options  as  contained  in  the  two  provided  makefiles. 

c.  Software  Prerequisites 

Perl  must  be  installed  on  the  platform  on  which  the  software  will  be  installed.  On 
Windows®-based  systems,  the  latest  version  of  Perl  from  ActiveState  Software  Inc. 
(www.activestate.com)  is  recommended.  The  Perl  modules,  Perl/Tk  and  Date::Manip,  must 
be  installed  for  this  script  to  work.  These  third-party  modules  are  available  through  the 
World  Wide  Web  (WWW)  at  the  Comprehensive  Perl  Archive  Network  (CPAN) 
(www.cpan.org).  The  ActiveState  version  has  Perl/Tk  bundled  with  the  core  Perl 
installation.  An  existing  ADCIRC  Grid  and  Boundary  Information  File  (fort.  14)  must  be 
present  in  the  current  working  directory  for  certain  options  to  work. 

The  standalone,  external  Perl  script,  delt_interact.pl,  must  be  present  in  the  same  location  as 


6 


the  GUI  installation  for  proper  execution  of  the  time  step  calculations  and  coordinate 
transformations  using  the  Carte  Parallelo-Grammatique  Projection  (CPP).  Additionally,  the 
external,  standalone,  Fortran  90  tidal  parameter  programs,  tide Jac.f  and  extract _gren.F, 
must  be  present  (see  §  1  d  for  details)  to  allow  computation  of  the  tidal  parameters.  Although 
the  GUI  software  is  platform-independent,  the  standalone  Fortran  programs  must  be 
compiled  for  each  platform  on  which  they  are  installed.  A  binary  tidal  parameter  database 
file  also  must  be  installed.  A  copy  of  this  file,  or  a  symbolic  link  to  it,  must  be  present  in  the 
user’s  current  working  directory.  Lastly,  several  Graphics  Interchange  Format  (GIF)  image 
files  must  reside  in  the  installation  directory.  These  programs  and  files  are  described  in  §  Id. 

d.  Installation 

The  makefortl5gui.pl  utility  is  located  in  the  ADCIRCUtilities  repository  in  the  Makefl5 
directory.  The  directory  has  the  following  contents: 

•  CONTENTS 

•  (directory)  Documentation/ 

o  CONTENTS 

o  ADCIRC_MAUAL_MakeF15_FINAL_09-25-2007.pdf 
o  README,  makefortl  5gui 

•  adcirc_banner_tiny.gif 

•  delt_interact.pl 

•  (directory)  fortran/ 

o  adcircjbc.f 
o  grenoble99.f 
o  tide  Jac.f 

•  makefortl  5gui.pl 

•  navo_log.gif 

•  nrlicon.gif 

•  nrltiny.gif 

•  param_defs_test.txt 

The  tidal  node  factor  and  equilibrium  argument  processing  program,  tide Jac.f  should  be 
compiled  manually  in  the  fortran  subdirectory.  The  Grenoble  FES99  database  and  associated 
extraction  software  are  located  in  the  ADCIRCUtilities  repository  in  the 
Boundary_Processing/Forcings/Tidal/Constituents/Grenoble_FES99  directory.  The  files  of 
interest  are  as  follows: 

•  tide_gren.dat 

•  tide_gren.f 

•  extract _gren.F 

•  tablk2.f 

•  Makefile 

•  Makefile gfor.w32 
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Step  1:  Compilation 

The  Grenoble  FES99  database  extraction  program,  extract _gren.F,  should  be  compiled  using 
the  supplied  Makefile.  An  alternative  makefde,  Makefile  gfor.w32,  is  supplied  for  use  on 
Windows®-based  systems. 

(OPTIONAL)  Step  2:  Define  Environmental  Variables  for  Tidal  Parameter  Programs 

Two  environmental  variables  may  be  set,  TIDE_PROGl  and  TIDE_PROG2,  which 
identify  directories  other  than  the  default 

ADCIRC_Utilities/Boundary_Processing/Forcings/Tidal/Constituents/Grenoble_FES99 
directory  for  the  tidal  database  programs.  These  user-specified  directories  define  the  location 
of  tidal  database  programs  if  the  user  has  a  non-standard  installation.  Examples  for  setting 
the  environmental  variables  in  C  shell  (csh)  and  Bourne  shell  (sh)  are  as  follows: 

cslv.  setenv  TIDE_PROGl  "/path/to/tide_f ac" 

csh:  set env  TIDE_PROG2  "/path/to/extract_gren . x" 

sh:  set  TIDE_PROGl="/path/to/tide_fac" ; export  TIDE_PROGl 

sh:  set  TIDE_PROG2="/path/to/  extract_gren . x" ; export  TIDE_PROG2 

in  which  the  actual  paths  of  the  programs  are  specified  in  place  of  “/path/to/.”  If  the 
environment  variables  are  not  set,  the  default  directories  are  used,  and  a  message  to  that 
effect  is  printed  in  the  command  window  from  which  the  program  was  invoked. 


2.  Fort  15  Creation:  Using  the  makefortl5gui.pl 

a.  Execution 

The  recommended  method  for  starting  the  GUI  is  from  the  command  line  in  a  command 
prompt,  or  terminal  window.  The  user  changes  to  the  appropriate  working  directory  and 
verifies  that  the  correct  fort.  14  and  fort.  15  files  are  present.  An  existing  fort.  15  file  is  needed 
only  if  the  user  wished  to  edit  that  file.  The  tidal  database  file,  tide_gren.dat  (see  Installation 
instructions,  §  Id)  also  must  be  present  if  tidal  parameters  are  to  be  calculated. 

To  start  the  GUI,  the  user  invokes  the  Perl  script  makefortl5gui.pl  from  the  command  line  as 
follows: 

#  makefortl5gui.pl 

The  full  path  name  must  be  included  if  the  directory  containing  the  GUI  program  is  not  in  the 
user’s  path  (see  Installation,  §  Id). 

As  presented  in  §  1  a,  sequential  views  of  the  GUI  are  shown  in  Figures  1  through  4. 
Navigation  within  the  GUI  is  the  same  as  for  other  window-based  applications:  using  the 
mouse  or  other  pointing  device,  or  by  using  the  keyboard  (i.e.,  the  four  arrow  keys,  Tab  key, 
Page  Up  and  Page  Down  keys  -  not  fully  supported).  Menu  items  also  can  be  navigated  in 
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the  standard  way  using  the  mouse  or  keyboard  (e.g.,  Alt-F  to  select  the  File  menu,  then  O  to 
select  the  Open  menu  item  -  not  fully  supported). 

If  an  existing  fort.  15  file  is  located  in  the  user's  current  working  directory,  the  GUI  program 
reads  that  fort.  15  file  after  generating  the  GUI.  If  no  such  file  is  present,  the  program  loads 
default  values  for  the  parameters  (except  for  boundary  forcing  values  and  tidal  parameter 
arrays).  Additionally,  the  user  can  have  the  GUI  read  in  an  existing  fort.  15  file  by  selecting 
the  File  — »  Open  menu  item,  which  opens  an  Open  File  dialog  as  shown  in  Figure  5. 


Figure  5.  The  Open  file  selection  dialog  window. 


The  file  selection  dialog  window  shown  in  Figure  14  has  a  look  and  functionality  that  is 
common  to  most  window-based  applications.  The  user-supplied  fort.  15  file  can  have  any 
name  supported  by  the  system.  After  the  fort.  15  file  name  has  been  entered,  the  user  is 
prompted  to  open  a  new  grid  file  (fort.  14)  as  shown  in  Figure  6.  If  the  user  selects  ‘Yes’,  then 
an  Open  File  dialog  appears  similar  to  that  shown  in  Figure  5. 


Figure  6.  The  Window  Prompt  for  opening  a  new  grid  (fort.  14)  file. 


If  there  is  an  existing  fort.  14  file  in  the  user's  current  working  directory,  the  GUI  program 
automatically  reads  it  in  after  startup.  If  none  is  found,  an  error  message  is  issued  (see  Figure 
7)  and  the  user  is  prompted  for  a  file  name.  It  is  crucial  that  the  fort.  14  file  corresponds  to 
the  fort.  15  file  in  use,  particularly  if  an  existing  fort.  15  file  has  been  read  by  the  software.  If 
an  existing  fort.  14  file  is  read  at  program  startup  and  an  existing  fort.  15  file  also  is  read  at 
startup  or  opened  later,  the  software  has  no  method  for  determining  whether  the  files 
correspond  to  one  another,  even  if  the  comments  at  the  beginning  of  the  two  files  indicate 
such  a  correspondence.  The  number,  location,  and  type  of  boundary  nodes  are  defined  by  the 
grid  file  (fort.  14)  and  used  by  the  fort.  15  file  when  extracting  and  assigning  boundary  forcing 
information.  It  is  therefore  incumbent  on  the  user  to  exercise  diligence  to  ensure  that  the 
fort.  14  and  fort.  15  files  correspond  to  one  another.  Creating  a  new  fort.  15  file  through  the 
GUI  is  one  way  to  ensure  that  the  fort.  15  file  is  compatible  with  an  existing  fort.  14  file. 
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ERROR:  Default  fort.14  grid  file 
(/home/linzell/progs/src/fort.14)  is 
missing  or  empty.  Enter  the  name  of  the 
file  to  use... 


Figure  7.  The  ERROR  popup  issued  if  a  fort.  14  grid  file  needed  but  not  found. 

Upon  completion  of  the  input  for  a  fort.  15  file  via  the  GUI,  the  new  fort.  15  file  is  saved  by 
selection  of  the  File  — >  Save  menu  item  as  shown  in  Figure  8. 


Figure  8.  The  Save  file  selection  dialog  window. 


By  default,  the  file  is  named  “fort.  15”  but  the  user  can  choose  to  save  and  rename  the  created 
fort.  15  file.  Note  that  the  GUI  will  append  the  file  extension  ".15"  to  the  user-supplied  file 
name.  If  a  file  with  the  same  name  already  exists  in  the  current  working  directory,  the 
program  prompts  the  user  for  whether  to  overwrite  the  file.  An  example  of  this  prompt  is 
shown  in  Figure  9. 


Figure  9.  The  File  Overwrite  user  prompt  window. 


If  the  user  chooses  to  overwrite  the  file,  the  new  file  replaces  the  existing  file  version. 
Otherwise,  the  file  selection  dialog  reappears  and  the  user  chooses  a  different  name  for  the 
output  file,  or  cancels  the  save  operation  altogether. 

b.  Specifications 

Many  parameters  within  the  GUI  are  relationally  driven,  that  is  parameters  are  disabled  or 
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enabled  depending  on  the  values  of  related  parameters.  For  example,  if  the  default  values 
initially  are  loaded,  the  2-D  option  is  selected,  and  the  3-D  parameters  (in  the  bottom  half  of 
the  GUI)  are  disabled  and  colored  gray  as  shown  in  Figure  4.  Changing  from  2-D  to  3-D 
model  operation  enables  the  3-D  parameters  and  any  other  related  parameters  that  are  above 
the  3-D  section,  as  shown  in  Figure  10. 


Figure  10.  The  enabled  3-D  section  of  the  GUI  after  selection  of  the  3-D  model  type 
parameter,  IM  =  1 . 


There  are  numerous  other  instances  in  which  the  values  of  certain  parameters  activate  or 
deactivate  other  related  parameters.  The  logic  governing  the  parameter  inter-relationships 
are  discerned  from  the  parameter  definitions  found  in  the  official  ADCIRC  model 
documentation  at  http://www.adcirc.org/documentation/fort.  15.html.  The  GUI  contains 
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several  different  types  of  GUI  elements,  or  “widgets,”  for  various  parameters  (e.g.,  Figure 
11).  These  were  described  in  detail  in  §  1  a.  The  GUI  elements  include  text  box  entries  in 
which  the  user  modifies  or  replaces  the  value  in  the  box.  Acceptable  values  span  the  range  of 
arbitrary  text,  floating  point,  and  integer  values.  Examples  are  the  entry  boxes  for  KP  and 
ZOS  in  Figure  10.  Parameters  which  must  be  selected  from  a  list  of  several  specific  values 
have  a  pull-down  list  of  values  from  which  to  select.  An  example  of  this  type  of  widget  is 
IGC  in  Figure  10.  The  user  clicks  on  the  underlined  arrow  icon  on  the  right  side  of  the 
widget,  and  the  list  appears  with  the  available  values.  The  user  selects  the  desired  value,  and 
the  list  disappears  with  the  chosen  value  displayed  in  the  widget. 

Parameters  which  can  take  one  or  more  values  from  a  list  of  values  have  a  pull-down  list  in 
which  one  or  more  values  can  be  selected  with  the  mouse  by  clicking,  shift-clicking,  or 
control-clicking,  as  appropriate.  Figure  1 1  displays  an  example  in  which  the  first  tidal 
constituent  in  the  Constituent s)  list  (Ql)  is  selected  by  clicking  with  the  mouse,  and  the 
second  (Kl),  which  is  not  adjacent  to  Ql,  is  selected  by  holding  the  Control  key  and 
simultaneously  clicking  with  the  mouse  (i.e.,  control-clicking). 

Parameters  in  which  one  value  must  be  selected  from  among  two  to  four  values  are 
represented  by  radio  buttons.  When  one  value  is  selected,  the  others  are  automatically 
deselected.  An  example  can  be  seen  in  Figure  1 1  under  the  Friction,  Diffusion,  Viscosity 
Parameters  panel.  The  value  of  NWP  can  range  from  0  to  2.  In  Figure  11,  NWP  has  been  set 
to  0,  so  the  other  values  of  NWP  (1  or  2)  have  been  deselected. 

Several  parameters  can  be  enabled  or  disabled,  respectively,  by  selecting  or  deselecting 
checkboxes  prior  to  performing  some  operation.  For  example,  Figure  1 1  shows  three 
checkboxes  for  NTIF,  NBFR,  and  NFFR,  respectively,  above  the  button  labeled,  “Generate 
Tidal  Parameters.”  The  checkbox  for  NTIF  has  been  selected  since  NTIF  has  a  value  of  2. 
The  checkbox  for  NBFR  has  been  deselected  since  NBFR  has  a  value  of  0.  The  checkbox 
for  NFFR  has  been  deactivated,  as  has  the  text  entry  box  for  NFFR;  boundary  information 
within  the  grid  file  (fort.  14)  since  has  triggered  deactivation  of  thee  NFFR  parameter. 

Some  parameters  are  comprised  of  arrays  of  values,  such  as  station  coordinates,  or  sigma 
levels.  For  these  parameter  types,  a  text  entry  widget  is  used,  as  shown  later  in  Figures  19 
and  22.  This  type  of  widget  allows  the  user  to  enter  values  manually,  copy  and  paste  the 
values  from  another  window  (e.g.,  a  text  editor),  or  input  the  values  from  an  existing  ASCII 
text  file.  Columnar  data  can  be  comma-delimited  or  space-delimited.  The  entry  widgets  have 
brief  messages  describing  the  options. 
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MakeFortl5  -  makefortl5gui.pl 


N  i~  I 

Figure  11.  GUI  features  include  a)  the  selection  of  non-adjacent  list  items  shown  by  the 
highlighted  “Constituents”  “Ql”  and  “Kl”,  b)  radio  buttons  for  selecting  parameter  values  as 
evidenced  by  the  selection  of  NWP  =  0  under  the  Friction,  Diffusion,  Viscosity  Parameters 
panel  and,  c)  the  enabling  and  disabling  of  checkboxes  evident  for  NTIF  and  NBFR, 
respectively. 


If  a  file  is  chosen  for  input,  a  message  is  displayed  as  shown  in  Figure  12  describing  the 
required  format.  Then  an  open  file  selection  dialog,  similar  to  that  shown  in  Figure  5 
appears. 


13 


NOTICE 


Note:  The  input  file  MUST  be  ASCII  text 
and  MUST  contain  at  least  two  columns: 

I  the  1  st  column  contains  the  Longitude 
value(s),  and  the  2nd,  the  Latitude 
value(s). 


Ok 

1 _ — 

Figure  12.  Example  of  a  text  entry  widget  where  the  message  describes  the  format  of  an 
ASCII  text  input  file. 


If  no  file  is  selected,  a  notice  is  displayed  (Figure  13)  prompting  the  user  to  try  file  selection 
again. 


Figure  13.  GUI  message  indicating  that  no  input  file  was  chosen;  prompts  the  user  to  try 
again. 


Once  an  input  file  is  selected  and  read,  a  status  message  is  displayed  indicating  the  number  of 
records  read.  An  example  is  shown  in  Figure  14. 


Figure  14.  GUI  status  message  indicating  the  number  of  records  read  from  an  input  file. 

This  section  has  provided  some  quick  start  instructions  and  a  general  overview  of  the  GUI 
functionality  and  features.  The  detailed  operation  of  each  parameter  panel  in  the  GUI  is 
described  in  §3.  Details  information  on  the  definitions  and  dependencies  of  various 
parameters  can  be  found  in  the  online  ADCIRC  model  documentation: 
http://www.adcirc.org/documentation/fort  15.html. 


3.  Details  of  GUI  Panel  Functionality 

Note  below  that  although  a  mouse  is  used  to  describe  navigation  and  interaction  within  the 
GUI,  any  supported  pointing  device  will  work.  Though  the  keyboard  also  can  be  used  for 
navigation  and  interaction  this  option  at  present  is  not  fully  supported  (see  §6).  Since  the 
mouse  is  the  most  commonly  used  pointing  device,  it  will  be  assumed  in  the  following 
descriptions. 
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a.  The  General  Program  Options  Panel 


The  topmost  GUI  panel  containing  fort.  15  parameters,  shown  in  Figure  1,  is  labeled  General 
Program  Options.  As  its  name  implies,  this  panel  contains  many  of  the  general  options  that 
control  how  the  model  is  run,  such  as  whether  a  2-dimensional  (2-D)  or  3-dimensional  (3-D) 
run  is  to  be  executed.  Other  option  groups  within  this  panel  include  Hot/Cold  Start 
parameters,  Nonlinear  Program  parameters,  and  Output  Option  parameters. 

This  panel  contains  three  types  of  GUI  elements,  or  “widgets.”  The  first  is  the  radio  button, 
which  is  a  set  of  two  or  more  toggling  buttons  grouped  together.  Only  one  of  the  buttons 
within  a  group  can  be  selected.  When  one  button  is  selected,  the  others  are  deselected.  In 
Figure  1,  for  example,  the  “Type  of  Run”  buttons  allow  the  user  to  select  either  2-D  or  3-D 
model  operation,  but  not  both. 

The  next  type  of  widget  is  the  text  entry  box.  This  is  a  text  box  in  which  a  value  or  string  is 
displayed,  and  the  user  can  replace  or  modify  the  existing  value  or  string.  In  Figure  1, 
examples  are  the  TAUO  value  and  the  text  strings  for  RUNDES  and  RUNID. 

The  third  type  of  widget  in  this  panel  is  the  pull-down  list.  This  is  a  combination  of  a  button 
with  an  underlined  arrow,  a  list  of  available  values  that  appears  when  the  button  is  activated 
(clicked),  and  a  text  box  that  displays  the  current  value  of  that  parameter.  All  of  the  pull¬ 
down  lists  have  been  configured  so  that  the  user  cannot  enter  a  value,  but  can  only  select 
from  the  list.  In  Figure  1,  the  NWS  parameter  employs  a  pull-down  list. 

One  of  the  primary  features  of  the  GUI  is  that  the  inter-relational  control  of  parameters  is 
accommodated.  In  Figure  1,  for  example,  the  Type  of  Run  options  control  the  values  of  IM 
and  the  Hot/Cold  Start  Parameters,  as  well  as  the  availability  of  the  Output  Harmonic 
Analysis  Parameters  and  the  3-D  Model  Parameters  sections.  If  the  default  “2-D”  Type  of 
Run  is  selected,  then  IM  is  set  to  1,  and  the  Hot/Cold  Start  option  is  enabled.  The  Output 
Harmonic  Analysis  Parameters  are  also  enabled,  but  the  entire  3-D  Model  Parameters  section 
is  disabled  (e.g.,  Figure  3).  If  the  “3-D”  Type  of  Run  is  selected,  then  IM  is  set  to  0,  the 
Hot/Cold  Start  Parameters  are  disabled,  the  Hot/Cold  Start  option  is  set  to  Cold,  and  IHOT 
and  NHSTAR  are  set  to  0.  Similarly  for  selection  of  the  “3-D”  Type  of  Run,  Output 
Harmonic  Analysis  Parameters  are  disabled,  and  the  entire  3-D  Model  Parameters  section  is 
enabled  (except  for  those  3-D  parameters  which  are  controlled  by  other  parameters,  e.g.,  the 
3-D  Diffusion  Parameters). 

Considering  the  Hot/Cold  Start  Parameters,  if  the  Hot/Cold  Start  option  is  enabled  and  the 
user  selects  Hot,  a  pop-up  window  appears  prompting  the  user  to  select  the  Hot  Start  file  unit 
number.  This  window  is  shown  in  Figure  15. 


Figure  15.  User  prompt  for  the  Hot  Start  File  unit  number. 
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The  user  must  select  either  67  or  68,  which  determines  the  unit  number  of  the  file,  fort.  67  or 
fort.  68,  respectively,  to  be  read  in  for  initialization  of  the  hot  start  model  run. 

Numerous  other  parameters  identified  by  the  GUI  have  similar  behavior  in  which  the  value 
of  one  parameter  controls  the  values  and  availability  of  other  related  parameters.  The  fort.  15 
file  documentation  and  parameter  descriptions  provide  details  on  which  parameters  are 
interrelated  (http  ://adcirc .  org/ document/ fort_  1 5  .html) . 

b.  The  Time,  Wetting/Drying  Parameters  Panel 

The  second  panel  containing  fort.  15  parameters  is  labeled  Time,  Wetting/Drying  Parameters 
(Figure  1).  This  panel  contains  parameters  that  specify  the  model  time  step,  start  and 
reference  times,  durations  of  the  model  run  and  ramping  function,  and  select  various  wetting 
and  drying  options  available  within  the  model.  Most  of  these  parameters  are  accessed  via 
text  entry  boxes,  and  can  therefore  accept  any  reasonable  values.  Some  reference  time 
parameters  are  selected  from  pull-down  lists.  Activation  for  most  of  these  reference  time 
parameters  depends  on  the  value  of  NWS. 

The  Time,  Wetting/Drying  Parameters  panel  has  a  large,  rectangular  button  labeled,  “Get 
Recommended  DTDP,  SLAMO,  SFEAO  Values”.  The  user  can  click  on  this  button  to 
perform  calculations  to  estimate  time  step,  DTDP,  for  tidally  dominated  flows  (assuming  an 
M2  frequency  tide),  and  compute  geometric  mean  values  for  the  central  longitude  (SLAMO) 
and  latitude  (SFEAO)  of  a  particular  domain.  Such  values  identify  the  centroid  location  for 
the  CPP  coordinate  transformation.  If  ICS  is  set  to  1  (indicating  Cartesian  coordinates), 
calculated  CPP  centroid  coordinates  are  not  available  since  the  CPP  transformation  is 
unnecessary.  Once  time  step  and  centroid  calculations  are  complete,  a  pop-up  window 
appears  prompting  the  user  to  decide  whether  or  not  to  replace  current  values  of  DTDP  and 
SLAMO  and  SFEAO,  if  ICS  is  set  to  2  (indicating  spherical  coordinates).  Figure  16  shows 
the  user  prompt  for  the  case  in  which  ICS  is  2  and  all  three  parameters  have  been  computed 
and  are  available  to  replace  default  values.  Figure  17  shows  the  user  prompt  for  the  case  in 
which  ICS  is  1  and  only  the  time  step,  DTDP,  can  be  replaced.  If  the  user  chooses  to  replace 
the  existing  values,  the  newly  computed  values  appear  in  place  of  the  previous  values. 
Otherwise,  the  existing  values  are  retained. 

It  is  important  to  note  that  the  DTDP  and  SLAMO/SFEAO  parameter  calculations  can  be 
performed  only  if  a  valid  fort.  14  finite  element  grid  file  has  been  input.  If  the  user  clicks  the 
button  but  no  fort.  14  file  had  been  read  upon  program  startup,  and  none  can  be  found  in  the 
current  working  directory,  an  error  message  is  issued  by  a  popup,  displayed  previously  in 
Figure  7.  The  user  is  prompted  for  a  grid  file  name  (details  in  §2),  and  that  file  is  used  for  the 
calculations. 
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Replace  Values? 


Note:  Calculated  SLAMO  is  -88.5803233693193  W, 
SFEAO  is  29.5738838740142  N 
for  CPP  coordinate  transformation,  and 
DTDP  for  tidal ly  forced  flows  is  2.33385386756979  s. 

CAUTION:  There  is  no  "undo"  function  --  choose  carefully. 

Replace  DTDP  Replace  SLAMO/SFEAO 


Figure  16.  Activation  of  the  “Get  Recommended  DTDP,  SLAMO,  SFEAO  Values”  button 
results  in  a  user  prompt  for  replacement  of  the  time  step,  DTDP,  and  centroid  of  the  CPP 
projection  (SLAMO/SFEAO)  for  the  case  of  ICS=2. 


Figure  17.  Activation  of  the  “Get  Recommended  DTDP,  SLAMO,  SFEAO  Values”  button 
results  in  a  user  prompt  for  replacement  of  the  time  step,  DTDP,  only  for  the  case  of  ICS=1. 

c.  The  Spatial  Structure  Parameters  Panel 

The  Spatial  Structure  Parameters  Panel  (Figure  1)  contains  dimensional  parameters 
describing  the  structure  of  the  meteorological  forcing  file  activated  for  certain  values  of 
NWS.  This  panel  also  contains  the  centroid  coordinates  of  the  projection  for  the  CPP 
coordinate  transformation.  As  described  in  §3b,  CPP  center  coordinates  can  be  calculated 
only  if  ICS  is  set  to  2  (spherical  coordinates)  and  a  fort.  14  file  has  been  read.  The  user  can, 
however,  manually  modify  the  values  SLAMO  and  SFEAO  regardless  of  the  value  of  ICS, 
though  for  ICS  set  to  1,  these  values  are  ignored.  All  of  the  parameters  in  this  panel  are 
contained  in  text  entry  boxes. 

d.  The  Friction,  Diffusion,  Viscosity  Parameters  Panel 

The  Friction,  Diffusion,  Viscosity  Parameters  Panel  (Figure  1)  contains  a  set  of  radio  buttons 
and  several  text  entry  boxes  for  bottom  friction,  horizontal  eddy  viscosity  and  transport 
diffusivity  parameters.  These  parameters  are  enabled  or  disabled  based  on  the  values  of  IM 
and  NOLIBF. 

e.  The  Tidal  Potential  and  Periodic  Elevation/Flux  Boundary  Forcing  Parameters 
Panel 

This  panel  (shown  in  Figure  2)  contains  text  entry  boxes  for  four  of  the  relevant  fort.  15  file 
parameters,  and  as  well  as  several  widgets  for  generating  the  remaining  periodic  (tidal) 
forcing  parameters.  The  four  text  entry  boxes  contain  the  values  of,  respectively,  NTIF, 
NBFR,  ANGINN,  and  NFFR.  Changing  the  value  of  NTIF,  NBFR,  or  NFFR  (if  enabled) 
also  selects  or  deselects  (if  zero)  the  checkboxes  on  the  right  side  of  the  panel.  A  value  of 
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zero  for  NTIP  automatically  assigns  a  zero  value  to  the  NTIF  parameter. 

To  perform  tidal  parameter  calculations,  the  date  and  time  assigned  by  the  user  to  the  start  of 
the  ADCIRC  model  run  are  entered  using  the  widgets  in  the  Start  of  Run  sub-panel.  The 
year  is  entered  manually,  and  must  be  between  1900  and  2100,  inclusive.  The  default  year  is 
the  current  system  year  at  the  time  the  GUI  is  started.  The  month,  day,  and  hour  are  selected 
from  pull-down  lists.  The  defaults  for  these  are  00  hours  on  January  1. 

Once  the  Start  of  Run  parameters  have  been  set,  the  tidal  constituents  can  be  selected.  Nine 
constituents  are  available,  including  the  principal  diurnal  and  semi-diurnal  components.  The 
steady  component  also  can  be  included  by  selecting  the  indicated  checkbox.  Note  if  the 
steady  component  is  included,  the  values  of  NBFR  and/or  NFFR  are  automatically 
incremented  by  1.  The  steady  component  is  not  available  to  the  tidal  potential  forcing 
option.  At  least  one  constituent  (not  including  the  steady  component)  must  be  selected  from 
the  scrolling  list.  If  more  than  one  constituent  is  needed,  the  user  can  click  on  the  first 
constituent,  and  then  shift-click  (press  the  Shift  key  and  then  click)  on  the  last  needed 
constituent  to  select  all  from  the  first  to  the  last.  If  non-adjacent  constituents  are  needed,  the 
user  can  control-click  (press  the  Control  key  and  then  click)  on  the  desired  constituents. 

After  all  desired  constituents  are  selected,  the  user  clicks  the  Generate  Tidal  Parameters 
button  to  generate  the  tidal  parameters.  One  or  both  of  the  standalone,  external,  Fortran  90 
tidal  programs  (see  §  lb,  #3  and  #16)  are  then  executed.  Only  tidal  parameters  corresponding 
to  the  selected  checkboxes  for  NTIF,  NBFR,  or  NFFR  are  generated.  If,  for  example,  the 
checkbox  for  NTIF  is  selected  and  the  others  are  deselected,  then  only  the  parameters  TPK, 
AMIGT,  ETRF,  FFT,  and  FACET  are  generated.  Similarly,  if  only  the  checkbox  for  NBFR 
is  selected,  then  only  the  parameters  AMIG,  FF,  FACE,  EMO,  and  EFA  are  generated.  If  the 
checkboxes  for  both  NTIF  and  NBFR  are  selected,  then  all  of  these  parameters  are  generated. 

If  the  user  selects  checkboxes  for  any  of  NTIF,  NBFR,  or  NFFR  on  the  right  side  of  the  panel 
and  there  is  a  discrepancy  between  the  values  of  NTIF,  NBFR,  or  NFFR  and  the  number  of 
selected  constituents  for  the  activated  checkboxes,  or  if  the  user  neglects  to  select  any 
constituents,  an  error  message  such  as  that  shown  in  Figure  18  appears.  The  user  is  advised 
to  correct  the  situation,  and  try  again.  Note  that  the  user  can  perform  tidal  calculations  for 
each  of  the  NTIF,  NBFR,  and  NFFR  parameters  individually  by  selecting  only  the  desired 
checkbox  at  the  right  of  the  panel.  In  this  case,  a  consistency  is  check  is  only  applied  to  that 
parameter  for  which  tidal  parameter  calculations  are  indicated.  This  action  can  be  repeated 
for  each  parameter,  NTIF,  NBFR,  and  NFFR  as  desired.  This  allows  the  specification  of 
different  numbers  and  names  of  constituents  for  each  of  the  tidal  potential  (NTIF),  elevation 
(NBFR)  or  flux  (NFFR)  period  boundary  forcing  parameters. 


Figure  18.  Example  error  message  for  inconsistent  input  in  the  Tidal  Potential  and  Periodic 
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Elevation/Flux  Boundary  Forcing  Parameters  Panel. 

It  is  important  to  note  that  the  tidal  parameter  calculations  can  be  performed  only  if  a  valid 
fort.  14  file  has  been  input.  This  also  is  noted  in  §2.  The  user  must  ensure  that  the  fort.  14  file 
corresponds  to  the  fort.  15  file  if  an  existing  fort.  15  file  is  being  modified.  If  no  fort.  14  file 
can  be  found  in  the  current  working  directory,  an  error  message  is  issued  as  seen  in  Figure  8. 
The  user  is  then  prompted  to  enter  a  new  grid  file  name,  and  if  a  valid  fort.  14  file  is  specified, 
the  calculations  are  perfonned. 

A  Help  Information  button,  indicated  by  an  “i”  label,  also  is  found  on  this  panel  (see  Figure 
2).  Details  about  this  button  can  be  found  in  the  discussion  of  Help  features  (see  §4). 

f.  Output  Station  Parameters  Panel 

The  Output  Station  Parameters  panel  (Figure  2)  contains  the  parameters  necessary  to  activate 
the  output  of  available  model  variables  at  specific  locations  or  stations.  The  format,  time 
window,  frequency,  number  of  stations,  and  station  locations  can  be  specified  for  elevation, 
current  velocity,  and  (if  enabled)  meteorological  and  concentration  time  series.  The  output 
format  flags  (NOUTE,  NOUTV,  NOUTC,  and  NOUTM)  are  selected  from  pull-down  lists, 
while  the  remaining  parameters  are  specified  in  text  entry  boxes.  If  the  number  of  stations 
for  the  different  variables  are  nonzero,  then  the  station  locations  can  be  input  by  using  a 
Position  Entry  Fonn  as  shown  in  Figure  19. 


Figure  19.  The  Position  Entry  Fonn  for  the  specification  of  station  location  coordinates  for 
the  station  output,  ICS  =  2. 

This  widget  has  the  same  number  of  input  lines  as  user-specified  stations.  If  the  user 
manually  enters  the  positions,  the  coordinates  should  be  entered  as  a  comma-delimited  or 
space-delimited  pair  on  each  line.  As  the  note  in  the  widget  indicates,  the  user  can  also  copy 
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the  coordinate  values  from  another  window  and  paste  them  into  this  widget,  or  provide  the 
name  of  an  ASCII  text  file  name  from  which  the  coordinates  are  subsequently  read.  Once  all 
coordinates  have  been  entered,  either  manually,  by  copy-and-paste,  or  file  read,  the  user 
clicks  the  Submit  button  to  complete  the  operation. 

As  seen  in  Figure  2,  the  Get  Position(s)  for  Which  Parameter(s)  sub-panel  contains  radio 
buttons  to  specify  the  order  of  the  coordinates,  either  longitude  followed  by  latitude,  or 
latitude  followed  by  longitude.  The  value  of  ICS  controls  whether  the  coordinates  are 
degrees  of  longitude/latitude  or  Cartesian  (i.e.,  X/Y  distances).  If  ICS  is  2,  then  the  sub¬ 
panel  and  entry  fonn  are  as  shown  in  Figures  2  and  19,  respectively.  If,  on  the  other  hand, 
ICS  is  1,  then  the  wording  is  changed  to  reflect  the  X/Y  or  Y/X  coordinate  system  (see 
Figure  20). 


Figure  20.  For  the  Output  Station  Parameter  panel,  wording  of  “Get  Position(s)  For  Which 
Parameter(s)?”  sub-panel  reflects  Cartesian  coordinate  options  when  ICS=1. 
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The  GUI  operation  is  unchanged;  only  the  wording  of  the  GUI  and  associated  widgets  is 
changed.  The  wording  in  the  position  entry  fonn  also  is  modified  accordingly,  as  shown  in 
Figure  21.  Similarly,  the  entry  of  the  coordinates  is  unchanged;  only  the  wording  is  changed. 


Figure  21.  For  the  Output  Station  Parameter  panel,  wording  of  Position  Entry  Fonn  sub¬ 
panel  reflects  Cartesian  coordinate  options  when  ICS=1. 


Note  that  availability  of  the  Meteorological  sub-panel  is  controlled  by  the  value  of  NWS,  and 
availability  of  the  Concentration  sub-panel  is  controlled  by  the  value  of  IM. 

g.  Global  Output  Parameters  Panel 

The  Global  Output  Parameters  panel  (Figure  2)  contains  parameters  controlling  model  output 
from  the  entire  model  grid.  As  for  the  Output  Station  Parameters  panel  (§3f),  the  output 
format  flags  are  specified  using  pull-down  lists,  and  the  remaining  parameters  are  specified 
in  text  entry  boxes.  Since  the  Global  Output  Parameters  apply  to  the  all  points  comprising 
the  grid,  no  input  of  coordinate  locations  is  necessary.  Similar  to  the  Output  Station 
Parameter  panel,  the  Meteorological  output  sub-panel  is  controlled  by  the  value  of  NWS,  and 
the  Concentration  sub-panel  is  controlled  by  the  value  of  IM. 

h.  Output  Harmonic  Analysis  Parameters  Panel 

This  panel  (Figure  2)  contains  parameters  associated  with  harmonic  analysis  of  the  model 
results.  Note  that  availability  of  this  panel  is  controlled  by  the  Type  of  Run  option.  If  Type 
of  Run  is  set  to  2-D  (the  default),  the  panel  is  enabled;  if  set  to  3-D,  it  is  disabled.  This  panel 
has  only  one  parameter  specifying  the  number  of  tidal  constituents  (NFREQ),  so  the 
“Generate  Tidal  Parameters”  button  on  the  right  need  only  be  activated  once.  The  text  entry 
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box  for  NFREQ  is  controlled  by  the  values  of  NHASE,  NHASV,  NHAGE,  and  HHAGV.  If 
any  of  these  parameters  is  set  to  1,  then  NFREQ  is  enabled.  If  NFREQ  is  set  to  a  value 
greater  than  zero,  then  the  Generate  Tidal  Parameters  button  is  enabled.  For  the  harmonic 
analysis  option,  up  to  thirty-seven  (37)  tidal  constituents  are  available  under  the 
“Constituents”  pull-down  menu  and  operation  of  the  Output  Harmonic  Analysis  Parameters 
panel  is  the  same  as  for  the  Tidal  Potential  and  Periodic  Elevation/Flux  Boundary  Forcing 
Parameters  Panel  described  in  §3e.  The  steady  component  also  can  be  included  by  selecting 
the  indicated  checkbox. 

i.  GWCE  Solver  Parameters  Panel 

The  GWCE  Solver  Parameters  panel  (Figure  3)  contains  parameters  controlling  the  type  of 
solver  to  be  used  for  the  generalized  wave-continuity  equation  (GWCE).  The  value  of 
ITITER  is  selected  by  clicking  one  of  the  two  radio  buttons.  The  value  of  ISLDIA  is  selected 
from  a  pull-down  list  and  the  two  remaining  parameters,  CONVCR  and  ITMAX,  are 
specified  using  text  entry  boxes. 

j.  3-D  Model  Parameters  Panel 

The  3-D  Model  Parameter  panel  (Figure  3)  serves  as  a  divider  between  the  upper  portion  of 
the  GUI,  with  general  and  2-D-specific  parameters,  and  the  lower  portion  containing  3-D 
model  specific  parameters. 

k.  3-D  Model  Input  Parameters  Panel 

The  3-D  Model  Input  Parameters  panel  (Figure  3)  contains  input  parameters  for  the  3-D 
model  option  pertaining  to  the  bottom  slip  condition  and  the  vertical  sigma  coordinate  grid. 
The  value  of  ISLIP  is  selected  from  among  three  radio  buttons.  The  value  of  IGC  is  selected 
from  a  pull-down  list,  and  the  remaining  parameters  in  this  panel  are  specified  using  text 
entry  boxes.  The  Enter  Sigma  Levels  button  is  enabled  or  disabled  according  to  the  value  of 
IGC.  If  enabled,  the  user  can  enter  the  sigma  levels  using  a  Data  List  Entry  Fonn,  as  shown 
in  Figure  22.  This  entry  form  is  similar  to  the  Position  Entry  Form  described  in  §3f;  the  user 
can  manually  enter  the  values,  copy  values  from  another  window  and  paste  them  into  the 
form,  or  read  values  from  a  user-specified  ASCII  text  file. 
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Figure  22.  From  the  3-D  Model  Input  Parameter  panel,  a  Data  List  Entry  Fonn  for  entering 
the  vertical  sigma  levels. 

l.  3-D  Eddy  Viscosity  Parameters  Panel 

The  3-D  Eddy  Viscosity  Parameter  panel  (Figure  3)  contains  parameters  related  to  vertical 
eddy  viscosity  and  turbulence  calculations.  The  value  of  IEVC  is  selected  from  a  pull-down 
list.  The  values  of  EVMIN  and  EVCON  are  specified  in  text  entry  boxes.  The  value  of 
IEVC  also  controls  the  text  entry  boxes  for  THETA  1  and  THETA2,  as  well  as  the  button 
labeled,  “Enter  Viscosity  Values  for  All  Sigma  Levels.”  In  a  manner  similar  to  the  sigma 
level  entry  described  in  §3k,  the  Data  List  Entry  Fonn  is  used  to  enter  eddy  viscosity  values 
associated  with  each  sigma  level. 

m.  3-D  Temperature/Salinity /Density,  Velocity,  and  Turbulence  Output  Parameters 
Panel 

This  panel  (Figure  3)  contains  parameters  that  control  the  time  series  output  of  3-D  model 
variables  at  user-specified  locations  or  stations.  These  parameters  are  analogous  to  the  2-D 
versions  described  in  §3f.  The  output  format  flags  are  specified  by  selecting  radio  buttons. 
The  other  parameters  are  specified  in  text  entry  boxes.  The  coordinates  of  the  output  stations 
are  entered  using  the  Position  Entry  Fonn  shown  in  either  Figure  19  for  latitude/longitude 
coordinates  or  Figure  21  for  X/Y  coordinates.  As  previously  described,  the  order  of  the 
coordinates  is  specified  by  selecting  the  appropriate  radio  button.  Wording  of  the  Get 
Position(s)  for  Which  Parameter(s)  sub-panel  and  the  Position  Entry  Form  reflect  the 
coordinate  system  specified  by  the  value  of  ICS  as  noted  earlier. 
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n.  3-D  Global  Output  Parameters  Panel 


This  panel  (Figure  3)  contains  parameters  for  the  control  of  time  series  output  of  model 
variables  for  the  entire  model  grid  (all  nodes).  As  for  the  Temperature/Salinity/Density, 
Velocity,  and  Turbulence  Output  Parameters  Panel  (§3m),  the  output  format  flags  are 
specified  using  radio  buttons,  and  the  remaining  parameters  are  contained  in  text  entry  boxes. 
Since  the  3-D  Global  Output  parameters  cover  the  entire  grid,  there  is  no  input  of  station 
coordinates. 

o.  3-D  Diffusion  Parameters  Panel 

This  panel  (Figure  4)  contains  four  parameters  specifying  lateral  and  vertical  diffusion 
parameters  for  salinity  (NLSD  and  NVSD,  respectively)  and  temperature  (NLTD  and  NVTD, 
respectively),  as  well  as  a  time  stepping  parameter  (ALP4).  All  are  specified  using  text  entry 
boxes.  Availability  of  these  widgets  is  controlled  by  the  value  of  IDEN. 


4.  Help  Features  of  the  GUI 

The  GUI  includes  a  comprehensive  help  facility.  All  model  parameters  and  buttons,  and 
numerous  descriptive  labels,  have  “Tool  Tips”  (also  known  as  “Bubble  Help”).  When  the 
mouse  pointer  is  placed  over  the  item  of  interest,  a  small  window  appears  near  the  pointer 
with  a  brief  description  of  the  item.  Figure  23  shows  an  example  Tool  Tip  for  the 
Wetting/Drying  model  option. 


Figure  23.  Display  of  the  Tool  Tip  for  the  Wetting/Drying  option,  an  example  of  the  “Bubble 
Help”  feature  of  the  GUI. 


Many  parameters  have  also  been  hyperlinked  to  Help  pages.  If  additional  information  is 
available  for  a  particular  parameter  than  is  shown  in  the  Tool  Tip,  the  user  can  click  on  the 
parameter  name  and  a  pop-up  window  appears  with  descriptive  text  for  that  parameter. 
Figure  24  demonstrates  the  hyperlinked  Help  associated  with  the  NFOVER  parameter. 


Type  of  Run  Wetting/Drying? 

pNFOVERf^  pICS  pIM—  p IDEN  |  p NRAMP  — 

2-D  ♦  3-D  ♦  Yes  ^  Ho 

*  U 

*Non-fatal  override  option  (click  link  for  details)  J  '  1 

Figure  24.  The  hyperlinked  parameter,  NFOVER,  indicates  the  availability  of  additional  Help 
information  on  that  parameter. 


Notice  that  the  Tool  Tip  has  a  note  informing  the  user  to  click  on  the  hyperlink  for  details. 
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Figure  25  shows  the  hyperlinked  pop-up  window  with  a  parameter  description  for  NFOVER. 
This  window  appears  when  the  user  clicks  on  the  hyperlink  for  NFOVER,  as  shown  in  Figure 
24.  Information  for  the  Help  description  windows  are  largely  derived  from  the  v45  online 
ADCIRC  model  manual  (http://documentation/fort  15.hl.ml).  Note  the  text  of  the  description 
can  be  copied  from  the  Parameter  Description  window  and  pasted  to  another  window  (e.g.,  a 
text  editor  or  an  e-mail  client). 


IIB  Parameter  Description  O  l 


NFOVER  -  non-fatal  error  override  option; 

J 

=  0,  inconsistent  input  parameters  will  cause  program  termination. 

-  1,  inconsistent  input  parameters  will,  (when  possible),  be 

automatically  corrected  to  a  default  or  consistent  value  and  execution 

continued.  Be  sure  to  read  the  nonfatal  warning  messages  to  see  whether 

any  parameters  have  been  modified.  Note  that  not  all  inconsistent 

parameters  can  be  corrected  automatically  and  therefore  fatal  error 

— 1 

messages  and  program  termination  may  still  result. 

/ 

OK 

Figure  25.  The  hyperlinked  Help  popup  for  the  parameter,  NFOVER. 


For  each  of  the  Panels,  Tidal  Potential  and  Periodic  Elevation/Flux  Boundary  Forcing 
Parameters  and  Output  Hannonic  Analysis  Parameters  (e.g.,  Figure  2),  an  information  button 
is  available,  indicated  by  an  “i”  label.  If  the  user  clicks  on  the  “i”  button,  a  pop-up  window 
appears  with  explanatory  text,  as  shown  in  Figure  26. 


NOTICE 


1 .  Nodal  factors  are  determined  at  the 
middle  of  the  record. 

2.  The  Greenwich  equilibrium  terms  are 
determined  at  the  beginning  of  the 
record. 

INPUT: 

WRITE(V)  ENTER  LENGTH  OF  RUN 
TIME  (DAYS)’ 

READ(V)  XDAYS 
WRITE(V)'  ENTER  START  TIME  - 
BHR.IDAY.IMO.IYR  (IYR  e.g.  1992)’ 
READ(V)  BHR.IDAY.IMO.IYR 
1  For  Equilibrium  Tide:  BHR-O;  IDAY-0; 
IMO=0;  IYR=0; 

NOTES: 

1 .  You  may  want  to  consider  eliminating 
the  spinup  period  from  the  LENGTH  OF 
RUNTIME 

2.  REFTIM  in  the  fort.15  file  must  be  set 

a)  at  the  start  of  the  period  (XDAYS) 
used  for  computing  the  tidal  factors 
Therefore  if  spinup  days  are  NOT 
included  in  the  tidal  factor  computation. 
REFTIM  =  SPINUP 


Ok 


Figure  26.  The  Information  window  describing  tidal  parameter  specification,  activated  by 
clicking  the  “i”  button  on  the  Tidal  Potential,  Elevation,  Boundary  Forcing  Parameters  Panel. 


The  text  for  the  “i”  buttons  are  contained  within  ASCII  text  files.  If  a  text  file  is  not  found 
upon  startup  of  makefortl5gui.pl,  a  notification  appears  instead  of  the  explanatory  text,  as 
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shown  in  Figure  27,  when  the  information  button  is  clicked.  If  this  occurs,  the  user  should 
attempt  to  locate  the  text  file  (README,  tidefacl  5)  and  move  or  copy  it  to  the  indicated 
directory.  See  §  Id  for  details  on  the  files  and  their  directory  paths. 


Figure  27.  Notification  of  a  missing  Information  text  file. 


In  addition  to  the  Tool  Tips  and  hyperlinked  Help,  the  Help  item  in  the  menu  bar  (e.g., 
Figure  20)  has  a  button  (Help  — >  Fort.  15  Help)  that  opens  a  web  browser  with  the  ADCIRC 
on-line  fort. 15  documentation  (http://adcirc.org/documentation/fort_15.html).  An  example 
of  the  documentation  displayed  in  a  browser  for  a  Linux  system  is  shown  in  Figure  28. 


Figure  28.  Browser  pointing  at  the  on-line  ADCIRC  model  documentation  for  the  fort.  15  file. 
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Note  that  the  on-line  version  may  not  necessarily  be  the  same  version  that  is  current  as  of  this 
writing.  This  version  of  makefortl5gui.pl  targets  ADCIRC  v45.1 1. 

Lastly,  the  Help  menu  has  an  additional  popup  window  item  (Help  — >  About)  that  provides  a 
listing  of  the  names  and  e-mail  addresses  of  the  principle  investigator  and  author(s),  software 
versions,  and  dates  of  installation,  as  shown  in  Figure  29. 


Figure  29.  Help  About  window  with  NRL  contact  and  software  installation  information. 


5.  Error  Check  Provisions  in  the  GUI 

The  GUI  has  extensive  error  checking  built-in  so  that  erroneous  values  are  either  not  possible 
or  are  identified  before  the  fort.  15  file  is  written.  The  radio  buttons  and  pull-down  lists  are 
configured  so  that  only  the  values  that  are  shown  can  be  selected.  Additionally,  consistency 
checks  are  performed  where  possible  for  user-entered  parameters  that  are  related  to  other 
user-entered  parameter  (e.g.,  the  number  of  tidal  constituents  desired  vs.  the  number  of 
selected  constituents,  see  the  error  display  in  Figure  18).  Several  examples  were  discussed  in 
§3b  and  §3e.  For  insufficient  station  coordinate  entries  in  the  Output  Station  Parameter  panel, 
Position  Entry  Form,  Figure  30  shows  the  error  message  that  is  displayed  indicating  the 
number  of  station  entries  required. 


Figure  30.  Error  message  from  the  Output  Station  Parameter  panel  triggered  by  too  few 
station  coordinate  entries. 


The  number  entered  by  the  user  is  shown  in  parentheses  (“(3)”  in  Figure  30),  and  the  number 
expected  is  listed  in  the  second  sentence  of  the  message  (“22”  in  Figure  30).  If  more  points 
are  entered  than  were  specified,  a  warning  message  is  displayed  such  as  that  shown  in  Figure 
31.  The  extraneous  values  are  read,  but  only  the  user-specified  number  for  NSTAE, 
NSTAV,  NSTAM,  NSTAC  is  retained. 
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Figure  3 1 .  Warning  message  from  the  Output  Station  Parameter  panel  indicating  more  station 
location  records  were  input  than  were  read  in  according  to  the  station  number  parameter 
(NSTAE,  NSTAV,  NSTAM,  NSTAC). 


If  the  user  chooses  to  generate  arrays  for  parameters  not  shown  in  the  GUI,  such  as  tidal 
forcing  parameters,  boundary  forcing  values,  or  sigma  levels,  and  those  parameters  already 
exist,  a  pop-up  window  appears  prompting  the  user  to  choose  whether  or  not  to  replace 
existing  parameters.  Figure  32  shows  an  example  from  the  Tidal  Potential,  Periodic 
Elevation/Flux  Boundary  Forcing  Parameter  panel  in  which  several  of  the  tidal  potential 
parameter  arrays  of  interest  have  existing  values  and  the  user  is  prompted  for  whether  or  not 
to  replace  them.  If  the  user  response  is  “Yes,”  the  operation  proceeds  and  the  parameters  are 
replaced;  if  “No,”  the  operation  is  canceled  and  the  existing  parameters  are  retained. 


H 


Arrays 

V  Tl  P  OTAG/TP  K/AM I GT/ETR  F/F  FT/FAC  ET 

have  existing  values;  replace? 


Figure  32.  An  example  of  the  Replacement  prompt  from  the  Tidal  Potential,  Periodic 
Elevation/Flux  Boundary  Forcing  Parameter  panel  triggered  by  existing  values  for  the 
TIPOTAG,  TPK,  AMIGT,  ETRF,  FFT,  and  FACET  data  arrays. 


Entry  boxes  for  floating  point  or  integer  values  (see,  e.g.,  Figure  20)  have  been  designed  to 
prohibit  the  entry  of  non-numerical  values  (i.e.,  spaces,  symbols,  or  letters).  Note  however, 
as  of  this  writing,  the  ranges  of  the  user-input  parameters  are  not  checked.  It  is  therefore 
incumbent  on  the  user  to  ensure  that  realistic  and  reasonable  values  are  entered.  The 
ADCIRC  program  also  performs  checks  on  the  input  values,  so  invalid  or  nonsensical 
parameter  values  are  often  be  caught  before  the  model  execution  begins. 


6.  Known  Limitations 

The  software  described  in  this  document  was  developed  for  ADCIRC  version  45.1 1.  Other 
versions  of  the  ADCIRC  model  that  use  the  same  format  and  content  of  the  fort.  15  file  are 
supported.  But,  versions  that  contain  modifications  to  the  fort.  15  format,  content,  or 
dependencies  are  not  supported. 

The  software  does  not  check  to  ensure  that  the  specified  fort.  14  grid  file  and  the  fort.  15  file, 
if  read  in,  correspond  to  one  another.  Compatibility  is  only  guaranteed  when  a  new  fort.  1 5 
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file  is  created.  Careful  consideration  of  file  naming  and  directory  structure  conventions  is  a 
good  approach  that  can  help  avoid  inadvertently  mixing  compatible  grid  (fort.  14)  and  input 
parameter  (fort.  15)  files. 

While  restrictions  on  some  parameter  values  are  enforced  through  the  used  of  pull-down  lists, 
not  all  entered  parameter  values  are  checked  against  ranges  of  validity.  The  ADCIRC  model 
code  itself  performs  many  checks  of  this  nature,  so  this  is  not  perceived  to  be  a  crucial 
limitation  of  the  software. 

One  limitation  is  that  the  only  global  tidal  data  for  boundary  forcing  available  through  the 
GUI  at  this  time  is  the  Grenoble  FES99  tidal  database.  This  database  may  or  may  not  be  the 
most  appropriate  source  of  boundary  forcing  for  the  user’s  application.  Furthermore,  the 
Grenoble  FES99  database  must  be  installed  and  have  a  copy  or  a  symbolic  link  in  the  user's 
current  working  directory.  One  approach  to  address  this  issue  would  be  to  use  a  hard-wired 
path  for  the  database,  and  force  the  installation  to  use  that  path.  Section  Id  describes  the 
installation  procedure  delineating  the  files  and  directories  required  for  this  software. 

Note  that  all  Fortran  programs  associated  with  the  software  must  be  compiled  for  the 
platform  on  which  the  software  is  installed.  Considering  that  the  ADCIRC  model  code 
requires  the  same,  this  is  not  deemed  a  real  limitation. 

At  the  time  of  this  writing,  an  unresolved  issue  exists  in  which  text  entry  boxes  do  not 
operate  correctly  under  the  operating  environment  described  by  the  use  of  Linux  Fedora  Core 
6  running  on  32-bit  hardware.  Other  tested  operating  environments  for  which  the  software 
operates  without  issue  are:  Linux  Fedora  Core  6  running  on  64-bit  hardware  and  Windows® 
XP  Professional. 

Presently,  keyboard  navigation  and  interaction  with  the  pull-down  and  scrolling  lists  is  not 
supported.  Nor  is  navigation  using  the  keypad  cursor  control  keys  supported.  Checkboxes 
do  not  always  change  when  the  corresponding  value  changes.  For  example,  in  the  Output 
Station  Parameters  panel  (Figure  20),  if  value  of  NSTAE  changes,  the  checkbox  for  NSTAE 
may  not  be  selected  or  deselected.  Though  clicking  in  another  text  entry  box  causes  the 
associated  checkbox  to  be  selected  or  deselected  if  appropriate.  Future  upgrades  will  address 
such  enhancements. 
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